home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 2 / MacMania 2.toast / Demo's / Tools&Utilities / Programming / Mac wt 0.04 Folder / MacWT.fat 0.04 / Mac WT source / wt / world.doc < prev    next >
Encoding:
Text File  |  1994-05-06  |  6.9 KB  |  176 lines  |  [TEXT/MMCC]
  1. This is a quick description of the wt world file.  There's no guarantee that
  2. it will not be changing in the future, of course.
  3.  
  4.  
  5.  
  6. The world file itself may not make much sense without a discussion of the
  7. internal world structures.
  8.  
  9. The first thing to understand is that the world in wt is not truly three
  10. dimensional.  It is can not render general polygons.  It can handle either
  11. horizontal floors or vertical walls.  This limitation is key to wt's speed.
  12.  
  13. The world structure in world.h looks like this:
  14.  
  15. typedef struct {
  16.      Table *vertices;
  17.      Table *walls;
  18.      Table *regions;
  19.      Table *textures;
  20. } World;
  21.  
  22.  
  23. Definitions:
  24.     Vertices are points on a plane.
  25.     Walls connect two vertices and separate two regions.
  26.     Regions are not necessarily connected areas that
  27.         are surrounded by walls.
  28.  
  29. Here is the vertex structure from world.h:
  30.  
  31. typedef struct {
  32.      fixed x, y;
  33.      fixed tx, ty, proj;      /* transformed coordinates */
  34. } Vertex;
  35.  
  36. The important fields for this discussion are the x and y coordinates.  The
  37. other fields are not stored in the world field, but are generated each time
  38. a frame is rendered.  I'll cover that sometime when I describe how the
  39. renderer works.
  40.  
  41. Ok . . . the vertex structure is pretty basic.  Like the definition says, it's
  42. just a point in two-space.  The wall structure is more interesting:
  43.  
  44. typedef struct {
  45.      Vertex *vertex1, *vertex2;
  46.      Texture *surface_texture;
  47.      Region *front, *back;
  48.      fixed xphase, yphase;
  49.      fixed xscale, yscale;
  50.      Boolean opaque;
  51. } Wall;
  52.  
  53. vertex1 and vertex2 are the two wall endpoints.  surface_texture is the
  54. texture which is mapped on the wall.  xphase, yphase, xscale, and yscale
  55. control how the texture is drawn on the wall.  xphase and yphase are numbers
  56. between 0 and 1.  The determine where the origin of the texture is with
  57. respect to the origin of the wall.  The wall origin lies in the plane of the
  58. wall at vertex1 and height zero.  If the x and y phase are zero, then the
  59. texture origin coincides with the wall origin.  If the x and y phase are
  60. both 0.5, then the wall origin coincides with the center of the texture.
  61. The xphase and yphase fields are critical for getting wall sections to
  62. join seamlessly (you'll notice that this is not done in my current sample
  63. world files.  Adjusting the texture phases will be a function of a
  64. world editor program.)
  65.  
  66. While the scale fields of the wall structure do indeed control how the
  67. texture map is sized, the would be more appropriately called 'frequencies'
  68. (The incorrect name persists because I've been too lazy to change it.)
  69. X and y scale factors of 0.1 would make a single tile of texture cover
  70. one hundred times as much wall area (not one-hundreth as much.)
  71.  
  72. The opaque field is something that will be used in future versions of wt.
  73.  
  74. One thing that may puzzle you is the fact that there are no heights listed
  75. in the wall structure.  That's because the height of the wall is determined
  76. by the regions in front and in back of it.
  77.  
  78.  
  79. Here's the region structure:
  80.  
  81. typedef struct {
  82.      fixed floor, ceiling;
  83.      Texture *floor_tex, *ceiling_tex;
  84. } Region;
  85.  
  86. floor is the floor height and ceiling is the ceiling height.  I know this
  87. is obvious but I'll say it anyway:  floor_tex is the texture map which will
  88. appear on the floor of the region and ceiling_tex is the one which will appear
  89. on the ceiling.
  90.  
  91. Here's a simple diagram which should help you understand how region heights
  92. interact with walls.  The diagram depicts a edge-on view of a couple walls.
  93. This exact arrangement of walls occurs with the windows of the castle.
  94.  
  95.  
  96.                      wall 1         wall 2
  97.                        |              |
  98.           ==ceiling====|              |==ceiling===
  99.                        |===ceiling====|
  100.           wall 1         wall 1 back      wall 2
  101.           front             and           front
  102.                          wall 2 back
  103.                        |====floor=====|
  104.                        |              |
  105.           ====floor====|              |====floor====
  106.  
  107. (Sorry--no spiffy PostScript figures . . .)
  108.  
  109. I hope that it's clear from this diagram how everything works, because I
  110. can't think of an explanation to accompany it.
  111.  
  112. Here's an important rule to keep in mind when thinking about walls.  If
  113. you are standing within a closed loop of walls, then:
  114.  
  115.    - You are in front of the the walls if they are oriented clockwise
  116.    - You are in back of the walls if the are oriented counterclockwise
  117.  
  118. I mentioned before that regions need not be connected.  This may seem strange
  119. at first, but it's a very useful property for regions to have.  I'll again
  120. bring up the case of the castle windows:  all four of them are the same
  121. region.  The neat thing about this is that I can modify the height of the
  122. bottom of all windows by changing just one number:  the floor height of
  123. the windows' region.
  124.  
  125.  
  126. Now that you've been briefed on the internal world structure, the world
  127. file should be pretty easy to figure out.  It maps almost directly to
  128. the internal structure.
  129.  
  130. The world file consists of four parts: a texture block, a vertex block,
  131. a region block, and a walls block.  The four blocks must appear in this
  132. order.  Each block consists of an arbitrary number of entries.  The
  133. entries in all blocks each consist of the block name followed by a list
  134. of parameters.
  135.  
  136. Here are the formats for each type of world file entry:
  137.  
  138. texture <texture name> <texture file>
  139. vertex <x> <y>
  140. region <floor height> <ceiling height> <floor texture name> <ceiling texture>
  141. wall <start vertex #> <end vertex #> <texture name>
  142.      <front region #> <back region #>
  143.      <xscale> <yscale> <xphase> <yphase>
  144.  
  145.  
  146. There are a number of restrictions which must be observed in world files.
  147.  
  148. - Textures which are to be used as floors must be either 64x64 or 128x128.
  149.   (I'll eventually add support for 256x256 textures--it's trivial to do.)
  150. - Textures which are to be used as walls must have be 64 or 128 pixels
  151.   vertically and a power of two pixels horizontally.
  152. - Walls may not intersect.
  153. - Walls should not be more than 255 units long.  This is necessary in order
  154.   to avoid fixed point overflows.
  155. - Walls should not be shorter than 1/256 units.  This limitation is due
  156.   to fixed point roundoff errors.
  157. - Regions should not have heights less than -128 or greater than 127
  158.  
  159.  
  160. This description should make it clear that we'll need a more sophisticated
  161. world designer than a text editor.
  162.  
  163. The format of wt's worldfile is independent of the rendering engine.  Once
  164. the world data has be slurped into a world structure, it doesn't matter to
  165. the renderer how it got there.  This leaves open the possibility for
  166. alternate world file formats, like Russ Nelson's (nelson@crynwr.com) 
  167. orld in Tcl changes.  This patch lets wt use a Tcl program as a world
  168. file (and more . . .) and will eventually be integrated into the wt
  169. distribution.  There will be a lot more news on Tcl and wt in the near
  170. future.  (People who don't have Tcl:  don't worry--I'll continue to support
  171. the graphics engine with the old world file format as well.  It will be
  172. a compile time option.)
  173.  
  174.  
  175.  
  176.